PMG Documentation

# REST

# Convert JSON to XML

Action Function: The PMG Convert JSON to XML workflow action gives the workflow designer the ability to convert JSON to XML.

Action Outputs: The action will output either:

Successful – The action executed without error

Unsuccessful – An error occurred in converting the JSON to XML

Action Properties:

Label

A label for the action in the diagram

Properties

JSON Text

JSON formatted data that will be converted to XML.

String Variable Name

The output string variable name which will contain the resulting XML.

# Convert XML to JSON

Action Function: The PMG Convert XML to JSON workflow action gives the workflow designer the ability to convert XML to JSON.

Action Outputs: The action will output either:

Successful – The action executed without error

Unsuccessful – An error occurred in converting the XML to JSON

Action Properties:

Label

A label for the action in the diagram

Properties

XML Text

XML formatted data that will be converted to JSON.

String Variable Name

The output string variable name which will contain the resulting JSON formatted data.

# Remote REST Request

Action Function: The Remote REST Request action allows the workflow to communicate with external or internal REST based web services via remote registered agents.

Action Outputs: The action will output either:

  • Successful – The action executed without error

  • Unsuccessful – An error occurred in performing the REST call

Action Properties:

Label

A label for the action in the diagram

Properties

Remote Scenario

Specifies the remote scenario, managed from the Designer Menu Bar, Manage, Connector Configuration, ExecuteAs.Config.xml.

An example scenario is below.

<actionconfig>
    <scenario name="machineA">
        <!-- name:Specifies the name of the scenario to be used by the workflow action -->
        <relayServerCommMode>WebSocket</relayServerCommMode>
        <!-- Specifies the communications mode for the relay. If the node value is WebSocket, then WebSockets will be used for the connection. Otherwise, standard TcpClient is used. -->
        <useRelayServer>true</useRelayServer>
        <!-- When the node is “true”, specifies the connection will use a Relay Server, or if “false” or not present, then a direct TCP connection will be made. -->
        <proxyServer /><!-- Optional proxy server machine name or IP address -->
        <proxyPort /><!-- Optional proxy port to use -->
        <proxyUser /><!-- Optional proxy user if credentials are required -->
        <proxyDomain /><!-- Optional user domain for credentials if required -->
        <proxyPassword /><!-- Optional proxy password if required -->
        <relayConfig>
            <!-- NOTE: Multiple relayConfig nodes may be defined to specify a list of relays to try.This node specifies attributes for the relay server -->
            <ip>127.0.0.1</ip><!-- Specifies the machine name or IP address of the relay server -->
            <workflowPort>17001</workflowPort><!-- Specifies the network port of the Workflow Engine -->
            <retryDelayMs>1000</retryDelayMs><!-- Optional delay in milliseconds to retry a communication request -->
            <agentWaitMs>30000</agentWaitMs>
            <!-- Optional time in milliseconds to wait for a remote command to execute -->
        </relayConfig>
        <agentName>machineA</agentName>
        <!-- NOTE: multiple agentName nodes may be specified to establish a pool of agents to try to send commands -->
        <domain>DOMAIN</domain><!-- The domain name for the user to authenticate for the remote command -->
        <username>USERNAME</username><!-- The username to authenticate the remote command -->
        <password note="thisIsMethod2">Q…AA==</password>
        <!--The password of the remote user to authenticate the remote command -->
        <waitseconds>600</waitseconds>
        <!--The time to wait in seconds for the command to execute. -->
        <certName>Workflow Remote Agent Server</certName>
        <!-- The name of the certificate to be used when using TcpClient. The cert must be installed in the Personal folder for the local machine -->
        <authKey>qi…m</authKey> <!-- a shared secret key -->
    </scenario>
    <actionconfig>

Run Mode

This setting determines how the action will be executed.

  • New Process: The action will run within a separate execution scope, with the security context of the running service

  • New Process (As User): The action will run in as the user identity specified in the given scenario

Rest Scenario

Specifies the credentials and access details for the REST call. Scenarios for REST actions are defined within the “RESTActions.Config.xml” connector configuration.

See the REST Request action Authentication Scenario property documentation for more details

URL

This property is required and specifies the target URL to send the request.

Method

This select list contains all the methods available in the REST API. The method chosen will depend on the resource being contacted.

URL Parameters

Specifies URL parameters at the end of the URL string using the following syntax:

?firstName=John&lastName=Doe&role=Admin

The property window provides for these values to be set as key/value pairs.

Header Parameters

Header parameters for the REST call are specified as key/value pairs within the property window.

Charset

Specifies the character set to use. Options are UTF8, ASCII and Unspecified.

Request Body

This property defines the body of the request. This data is typically in JSON or XML format but could also be a text string, integer, or custom data type format. Configuration data for this property will depend on what the target expects.

Content-Type

This property allows the request to notify the target URL of the incoming data type (Content-Type) of the request body.

Accept

Setting this property allows the request to notify the target of the data type of the response body (accept type).

Web Timeout(sec)

This is the number of seconds allowed for a web request before it times out. A default value is used if a value is not provided. If the web service is slow or is returning or receiving a large amount of data, a value such as 600 seconds or larger can be supplied.

Variable For Storing Error Message

A variable where the error message will be stored if the REST request fails.

Variable Name to Store Expected Data

A string or object variable where the response data will be stored.

Variable Name to Store Expected Header Data

A string variable where the header data of the response will be stored.

Variable Name to Store Response Status Code

This is a workflow string variable where the response status code will be stored. For example, a successful request might produce a 200-status code and a request that failed due to a problem with authorization will return a 403 status code.

# REST Request

rest-request.png

Action Function: The REST Request action allows the workflow to communicate with external or internal REST based web services. In addition to setting the REST call properties through the action’s property panel, the action offers a “REST Builder” and “Postman Import” to set the action’s properties.

Note: Considerations for limitations, like the “Invoke Web Service” action, should be made when making direct REST calls within workflow, as the process designer is responsible for error handling, as well as any special knowledge for the REST service consumed.

Action Outputs: The action will output either:

  • Successful – The action executed without error

  • Unsuccessful – An error occurred in performing the REST call

Action Properties:

Label

A label for the action in the diagram

Properties

Authentication Scenario

Specifies the credentials and access details for the REST call. Scenarios for REST actions are defined within the “RESTActions.Config.xml” connector configuration.

Multiple authentication scenarios may be defined in the scenario configuration XML document. Basic Auth, NTLM, and Certificate Auth are supported.

Sample scenarios:

<scenarios>
  <!-- The generic rest connector supports many different configuration scenarios, and can use no encryption (not recommended) or method 2 or method 3 -->
  <!-- Here is a scenario which uses basic authentication and no encryption -->
  <!-- The domain can be added to the username or it can be in a separate domain attribute -->
  <scenario name="MyExampleScenario1" username="username" password="password" encryptedpassword="false" type="BASIC"></scenario>
  <!-- Here is a scenario which uses basic authentication and method2 encryption -->
  <scenario name="MyExampleScenario2" username="domain\username" password="_method2_encrypted_password_" encryptedpassword="true" type="BASIC"></scenario>
  <!-- Here is a scenario which uses basic authentication and method3 encryption -->
  <scenario name="MyExampleScenario3" username="domain\username" password="_method3_encrypted_password_" encryptedpassword="true" encryptionmethod="3" type="BASIC"></scenario>
  <!-- This scenario uses method2 encryption and NTLM authentication -->
  <scenario name="MyExampleScenario4" username="username" domain="domain" password="_method2_encrypted_password_" encryptedpassword="true" type="NTLM"></scenario>
  <!-- This scenario uses certificate authentication -->
  <scenario name="MyExampleScenario5" checkcertrevocationlist="_true_or_false_" certpassword="_method2_encrypted_password_" encryptedcertpassword="true" certlocation=".pfx file path" type="CERT"></scenario>
  <!-- This scenario isn't using authentication, but uses tls and ssl attributes to set the accepted network tls and ssl settings -->
  <!-- If auth isn't needed on the scenario, set the type to TLSONLY. Otherwise, add the tls and ssl attributes to another REST scenario -->
  <scenario name="MyExampleScenario6" tls="true" tls11="true" tls12="true" ssl3="true" type="TLSONLY"></scenario>
  <scenario name="MyExampleScenario7" tls="false" tls11="false" tls12="true" ssl3="false" username="domain\username" password="_method2_encrypted_password_" encryptedpassword="true" type="BASIC"></scenario>
  <!-- In this scenario, OAUTH2 is used and the grant type is client_credentials. The client_secret must be encrypted with method2 -->
  <scenario name="MyExampleScenario8" type="OAUTH2" grant_type="client_credentials" clientid="_clientid_" clientsecret="_method2_encrypted_client_secret_" tokenurl="_token_url_"></scenario>
  <!-- In this scenario, OAUTH2 is used and the grant type is password. The client_secret and password must be encrypted with method2 -->
  <scenario name="MyExampleScenario9" type="OAUTH2" username="username" password="_method2_encrypted_password_" grant_type="password" clientid="_clientid_" clientsecret="_method2_encrypted_client_secret_" tokenurl="_token_url_"></scenario>
  <!-- This scenario uses a proxy and basic auth -->
  <scenario name="MyExampleScenario10" username="domain\username" password="_method2_encrypted_password_" encryptedpassword="true" type="BASIC" proxyaddress="_proxy_address_" proxyport="_proxy_port_" proxyusername="_method2_encrypted_proxy_username_" proxypassword="_method2_encrypted_proxy_password_"></scenario>
</scenarios>

TLS support

REST Scenarios support TLS 1.1 and TLS 1.2. You can control the tls, tls 1.1, tls 1.2, and ssl 3.0 options with parameters in RESTActions.Config.xml:

tls="false" tls11="true" tls12="true" ssl3="true"

It is also possible to set up a scenario for TLS only, without forcing BASIC auth. Set the type to TLSONLY:

<scenario name="TLS" tls="false" tls11="true" tls12="true" ssl3="true" type="TLSONLY" ="">

Custom OAuth support

Custom OAuth is supported using the attribute: custom_oauth

URL

This property is required and specifies the target URL to send the request.

Method

This select list contains all the methods available in the REST API. The method chosen will depend on the resource being contacted. Below is a description of each method.

GET

The GET method retrieves data from a specified URL, one of the most common methods. Components of a GET:

  • URL - the target

  • Headers - Additional information about the request

  • Response (Variable Name to Store Expected Data) - the message returned from the call

POST

The POST method sends data to a specified URL and gets a response, another very common method. POST is like a GET, except a Body of data is passed to the target URL. Components of a POST:

  • URL - the target

URL Parameters

  • Headers - Additional information about the request.

  • Body (Data to Pass) – The content being sent to the target url.

  • Response (Variable Name to Store Expected Data) - the message returned from the call.

PUT

The PUT method is almost identical to POST. In theory POST should be used when updating or creating a complete object. The PUT should be used when simply updating a piece of an object.

PATCH

The PATCH method is much like PUT in that it updates a resource, but unlike PUT, it applies a delta rather than replacing the entire resource.

DELETE

The DELETE method is just as it sounds. Usually used to delete an instance of an object.

HEAD

The HEAD method asks for the response identical to the one that would correspond to a GET request, but without the response body. This is useful for retrieving meta-information written in response headers, without having to transport the entire content. It is considered a lightweight call compared to the GET request.

OPTIONS

The OPTIONS method returns the available options that are available to a REST call.

TRACE

The TRACE method simply echoes the request in the response.

URL Parameters

Specifies URL parameters at the end of the URL string using the following syntax:

?firstName=John&lastName=Doe&role=Admin

The property window provides for these values to be set as key/value pairs.

Header Parameters

Header parameters for the REST call are specified as key/value pairs within the property window.

Charset

Specifies the character set to use. Options are UTF8, ASCII and Unspecified.

Datatype to Pass

This property allows the request to notify the target URL of the incoming data type (Content-Type) of the request body. Often, a target URL will accept a range of data types and this property specifying at call time what the data type will be. Typically, this value is Text, JSON, or XML. The value ‘Custom’ is also available in the Datatype to Pass select list. If this value is selected, it indicates that a custom value is supplied in the Custom Datatype to Pass property. Form With Files specifies a file will be submitted. To send files, map file data in the “Form Data To Pass” property.

Custom Datatype to Pass

This property is used when the data type to pass is something other than Text, JSON, or XML. For example, if the data being passed is in an Atom Syndication Format, application/atom+xml would be entered for this property.

Data to Pass

This property defines the body of the request. This data is typically in JSON or XML format but could also be a text string, integer, or custom data type format. Configuration data for this property will depend on what the target expects.

Form Data to Pass

This property defines values to pass as Form. This property supports common field types including File types. File values are specified as file paths to be uploaded, or individual file variables.

Datatype to Expect

Setting this property allows the request to notify the target of the data type of the response body (accept type). Often a target will return a range of data types and this property specifies at call time what the data type needs to be. Typically, this value is Text, JSON, or XML, but could be a custom type which is indicated with the ‘Custom’ select option.

Custom Datatype to Expect

This property is used when the data type to expect is something other than Text, JSON, or XML.

Web Timeout(sec)

This is the number of seconds allowed for a web request before it times out. A default value is used if a value is not provided. If the web service is slow or is returning or receiving a large amount of data, a value such as 600 seconds or larger can be supplied.

Variable For Storing Error Message

A string variable where the error message will be stored if the REST request fails.

Variable Name to Store Expected Data

A string or object variable where the response data will be stored.

Variable Name to Store Expected Header Data

A string variable where the header data of the response will be stored.

Variable Name to Store Response Status Code

This is a workflow string variable where the response status code will be stored. For example, a successful request might produce a 200-status code and a request that failed due to a problem with authorization will return a 403 status code.

# REST Builder

REST Builder provides an intuitive interface to define and test a REST connection. To access REST Builder for a REST action, right click the REST action in a diagram in edit mode and select the context menu, “REST Builder”. This will display a screen where various properties for the REST action may be defined as well as a test utility to simulate or validate configured REST calls at design time, without the need to deploy the workflow to test. The REST Builder provides for configuration for the REST call to be made, including Authorization, Params, Headers, Body, and Response. Additionally, special variables may be specified to store various responses for the REST call, from the “Response Variables” tab of the configuration. Response variables may be specified for expected data, errors, header data, and response status code.

Testing REST calls

Configuration for the REST call can be tested from the “Test Variables” tab of the REST Builder. Any workflow values used for the REST properties can be set with test values to try the REST call. From the “Test Variables” tab, click “Refresh Variables to Set” if needed and provide test values for the Variables listed. Click “Send” to test the call and see the response.

# Postman Import

Postman is a popular desktop application utility to interact with REST calls. Postman can export a configured REST call as a JSON definition file which may be pasted directly into a REST action through this Import feature, which will then set the respective action properties. To access Postman Import for a REST action, right click the action in a diagram in edit mode and select the context menu, “Postman Import”. A text input window is displayed where a Postman REST call definition can be pasted directly. Once the Postman JSON is pasted, click “Save and Close” to update the action properties based on the Postman definition.

← Office →